feat: add official AXI skill and fleet intake guidance - #149

Intent

The captain asked for a 'write-axi' skill: how to build an agent-ergonomic CLI to the AXI contract (source: https://axi.md/), and - first - the habit of checking whether one already exists, because this fleet twice in one day planned to build a tool that already existed (a Forgejo client filed 2026-08-17 when forgejo-axi was already published; and a plan that said 'adopt sc1's archive tool' when that tool had never been persisted).

The captain then redirected the task three times mid-flight, and those redirections are the intent, not the original brief:

1. STOP before writing skill content: an OFFICIAL AXI skill already exists at github.com/kunchenguid/axi, installable with 'npx skills add kunchenguid/axi'. Install and read it first, then decide: either this task produces NOTHING, or a thin fleet-specific overlay that POINTS AT the official one and adds only what is ours. Do not restate anything the official skill already says.
2. Sharpen the catalogue check: one index is not enough. forgejo-axi is on npm and NOT in the axi.md catalogue; docker-axi IS in the catalogue and 404s on npm. The two indexes disagree in BOTH directions, so the rule is: check the axi.md catalogue AND the package registry, and state which you checked alongside the result. Also: the repo ships packages/axi-sdk-js, so building an AXI tool is SDK work rather than hand-rolling; registering a tool is a pull request to catalog.yaml via CONTRIBUTING.md; absence from the catalogue means only that nobody added an entry, not that a tool is unofficial or unmaintained.
3. Final ruling, after the captain read the official skill from source: DO NOT WRITE A COMPETING SKILL. Instead install the official skill into this repo's tracked skill surface through the normal path, and place our four fleet-specific additions where they do not compete with it - check both indexes, tokens never on a command line and never emitted, licence and provenance rules for deriving, and the open ownership question. If a short pointer section is the right home rather than a skill, say so and do that; firstmate-coding-guidelines' one-owner rule governs.

So this change deliberately does NOT contain a fleet-written description of the AXI design contract. That absence is the point. The contract is installed verbatim from upstream at .agents/skills/axi/ (MIT, by Kun Chen) together with the installer's skills-lock.json manifest, and docs/axi-skill-provenance.md records the upstream commit 408a653, the install date, the content hash, and the MIT notice - which is also copied to .agents/skills/axi/LICENSE beside the copy.

Decisions made while doing the work, which a reviewer reading only the diff would not know:

• The installed file .agents/skills/axi/SKILL.md is upstream's and is deliberately NOT edited. It contains em dashes that this repository forbids in its own tracked Markdown, and its frontmatter lacks the user-invocable and metadata.internal fields that every skill this repository authors must declare. Both are intentional. Editing it would diverge it from the hash skills-lock.json records and turn the next 'npx skills add' update into a conflict. Do not 'fix' either one; docs/axi-skill-provenance.md and CONTRIBUTING.md both state this explicitly.
• Because of that, tests/fm-instruction-owners.test.sh's frontmatter trigger floor was changed to EXEMPT skills listed in skills-lock.json from the frontmatter half, while still requiring each to be reachable from AGENTS.md section 13 so an installed skill cannot become dead weight. The exempt set is read from the manifest via a new fm_installed_skill_dirs helper in tests/lib.sh rather than hardcoded, deliberately matching the existing reason that check enumerates the skills directory instead of keeping a list: a hand-maintained list goes stale silently.
• The fleet's four additions live in a SEPARATE skill, .agents/skills/axi-tool-intake/, not in the installed file and not as an AGENTS.md section. A skill was chosen over a pointer section on the placement tree in firstmate-coding-guidelines: roughly 100 lines of conditional detail that fires only at tool intake belongs in a skill with a section 13 trigger, not inline in AGENTS.md where every session pays for it, and it must never be mixed into vendored material that gets re-synced.
• It was renamed from the captain's original name 'write-axi' to 'axi-tool-intake' precisely because 'write-axi' would compete with the installed 'axi' skill in the harness skill listing and invite an agent to load the wrong one believing it had the design contract. The captain approved this rename after the fact.
• The overlay carries NO design guidance by construction and never names a principle of the contract; tests/fm-axi-tool-intake.test.sh enforces that with explicit negative assertions.
• Two corrections to the fleet's own briefing, resolved in favour of the measured source and recorded in the files: the Forgejo miss was fourteen days, not one (npm shows forgejo-axi 1.0.0 on 2026-08-03), and the axi.md catalogue would not have caught it at all since it still does not list it. The two-index disagreement is also wider than reported: jj-axi is catalogue-listed and 404s on npm as well as docker-axi.
• README.md previously claimed every skill under .agents/skills/ carries metadata.internal: true. This change falsified that claim, so the sentence was corrected rather than left standing.
• skills-lock.json was added to the tracked shared-material lists in AGENTS.md section 1 and CONTRIBUTING.md, because it is now tracked root material that governs .agents/skills/.

On tests: tests/fm-axi-tool-intake.test.sh asserts on prose and on a sha256, deliberately. Neither skill ships any code - what they carry is an attribution, a boundary between someone else's words and ours, and four rules whose entire value is that they are written down. The repository has established precedent for exactly this in tests/fm-codebase-sweep.test.sh and the domain-modeling attribution checks in tests/fm-instruction-owners.test.sh, both of which assert on adopted-material prose for the same reason: a dropped licence notice, a silently edited upstream file, or a fleet rule quietly reattributed to an external specification are all invisible at load time, because the skill still loads and still works. The sha256 assertion in particular is a real behavioral contract over an installed artifact: it detects a local edit to a vendored file that would break the installer's update path.

Nothing here writes, installs, or publishes an actual AXI tool - the captain's brief explicitly excluded that. Land as a true merge commit; this repository forbids squash.

What Changed

• Install the official AXI skill verbatim with its MIT license, lock manifest, and provenance record.
• Add a fleet-specific AXI intake skill covering catalogue and registry checks, credential handling, derivation provenance, and deployment ownership.
• Update skill ownership rules and contract tests to preserve vendored content while requiring installed skills to remain reachable.

Risk Assessment

✅ Low: The change is well-bounded, conforms to the stated intent, and the prior manifest-parsing and test-contract concerns are adequately resolved without introducing material source risk.

Testing

Inspected the focused diff, ran both targeted contract suites, and manually verified the end-user skill discovery/load surface and installer manifest; all checks passed, with command-output evidence captured and no UI screenshot needed because this change exposes instruction skills rather than a rendered interface.

AGENTS.md exposes `axi` as the verbatim official design contract and `axi-tool-intake` as the separate fleet overlay. `skills-lock.json` resolves `axi` to source `kunchenguid/axi`. The overlay presents exactly four intake areas: both-index discovery, credential handling, derivation provenance/licensing, and the open fleet ownership question.

Pipeline

Updates from git push no-mistakes